home *** CD-ROM | disk | FTP | other *** search
/ BCI NET 2 / BCI NET 2.iso / archives / programming / utilities / adf10.lha / ADF.doc next >
Encoding:
Text File  |  1994-12-13  |  5.0 KB  |  129 lines
  1.  
  2.                            The AutoDoc Formatter 1.0
  3.  
  4.                  (c) 1994 Martin Mares, MJSoft System Software
  5.  
  6. ================================================================================
  7.  
  8.  
  9. Preface
  10. =======
  11.  
  12.   ADF and its documentation are Copyright (c) Martin Mares, MJSoft System
  13. Software, Prague, Czech Republic.
  14.  
  15.    This  archive  can be freely redistributed, as long as all of its files are
  16. included   in   their  original  form  without  any  additions,  deletions  or
  17. modifications, and no more than a nominal fee is charged for its distribution.
  18. All  copyright  notices  in  the programs and accompanying documentation files
  19. must  remain  on  their places.  Also '.displayme' and other similar files may
  20. not be added.  This is generally known as FREEWARE.
  21.  
  22.    Special  permission is given to Fred Fish to distribute this program on his
  23. "Fish Disks".
  24.  
  25.    This  software  is  provided  "AS  IS" without warranty of any kind, either
  26. expressed  or implied.  The author is not responsible for any damage caused by
  27. it.
  28.  
  29.  
  30. Requirements
  31. ============
  32.  
  33.    ADF requires Kickstart 2.04 or higher and the ss.library version 4 or newer
  34. (it can be downloaded from the Aminet in archive SSLib<version>.lha).
  35.  
  36.  
  37. Introduction
  38. ============
  39.  
  40.    Some  years ago, CBM introduced a standard format for writing documentation
  41. of  libraries  and  other system modules - the Autodocs.  This is a relatively
  42. good  format  and is used by many programmers which are interested in creating
  43. of  additional  system  modules,  but it is a bit hard to maintain, because it
  44. contains  still  the  same  headers  for  each function and the parameters are
  45. described  on three different places.  The AutoDoc Formatter tries to simplify
  46. this hard work.
  47.  
  48.    This document doesn't explain the style rules of Autodocs.
  49.  
  50.    ADF  generates  the  doc  from  given  group  of  source  files  containing
  51. documentation material in comments.  Each block describing one function starts
  52. with  ??****  <funcname>  on  the  start  of  line.  The question marks may be
  53. replaced  by  any  characters (allows ADF to be used with Assembler, C, Pascal
  54. and  many  other  languages).   This  header  is  followed by doc lines of the
  55. following form:
  56.  
  57. ?* <command> <parameter>
  58.  
  59.    '?'  can  be  again  replaced  by  any  single  character, <command> is not
  60. required  (but  if  you specify no command, you have to write both the leading
  61. and  the  trailing  space  of  the  command  field  or  to use a TAB character
  62. instead).   The  second space can be replaced by a TAB.  Lines containing only
  63. the parameter are treated as a continuation of parameters of previous command.
  64. Lines  containing neither the command nor the parameter are considered to be a
  65. paragraph break.
  66.  
  67.    The function doc block is finished by line starting with ??****.
  68.  
  69.  
  70. Commands
  71. ========
  72.  
  73.    All standard commands consist of exactly one character.  Anything with more
  74. than  one  character  is treated as a custom heading and all underscores in it
  75. are automatically converted to blanks.
  76.  
  77.    If you specify a section header which is identical to the current one, only
  78. paragraph break will happen.
  79.  
  80. =    right-hand side of NAME chunk. If used more than once, it specifies
  81.     other whole lines appended to the NAME chunk. Must be specified before
  82.     any other chunks.
  83. i    declaration of input. Followed by: name,register,type = description.
  84.     ADF constucts SYNOPSIS and INPUT chunks from these declarations. Type is
  85.     needed only for C-language declarations. If no type is used, the second
  86.     comma may be omitted. If you enter no name, no real input will be
  87.     generated, only the description will be inserted as a paragraph to the
  88.     INPUT chunk. Such insertions are allowed only after all real parameters.
  89.     If no register name is given, D0 is assumed. Inputs and outputs  must
  90.     be specified after the '=' chunk and before all other chunks.
  91. r    declaration of result. Same syntax as 'i'.
  92. o    declaration of output. Same syntax as 'i'. Not inserted to SYNOPSIS.
  93. f    FUNCTION chunk.
  94. e    EXAMPLE
  95. n    NOTE
  96. b    BUGS
  97. s    SEE ALSO
  98. t    TAGS. Special indentation used.
  99. w    WARNING
  100. g    FLAGS. Special indentation used.
  101. !    Raw insertion. Current paragraph is flushed and the parameter is
  102.     inserted to output text before any processing except for indentation,
  103.     which is done always.
  104. >    Break current paragraph and increase indent level by 3 characters.
  105. <    Break current paragraph and decrease indent level by 3 characters.
  106. *    Comment (ignored).
  107. -    Itemization. New paragraph is started and the '-' sign is inserted
  108.     before new paragraph. Special indentation used.
  109.  
  110.  
  111. Special control lines
  112. ---------------------
  113.  
  114.    You  can  specify global prefix of all names (such as 'ghost.library').  It
  115. can  be  done  by  including  '??****  =<prefix>'  in  your source.  The slash
  116. character will be appended automatically.
  117.  
  118.    You  can  also set C or ASM mode by including '??**** #<mode>' (the mode is
  119. given in lower case).  In the ASM mode, no C declaration in the SYNOPSIS chunk
  120. are  generated and the data types in declarations of inputs/outputs/resultsare
  121. ignored.
  122.  
  123.  
  124. Final words
  125. -----------
  126.  
  127.    Send suggestions and bug reports to <mjsoft@k332.feld.cvut.cz>.
  128.  
  129.